home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / saveloa2.zip / GETKEY.DOC next >
Text File  |  1992-12-19  |  19KB  |  393 lines
  1.                                  GetKey ver 2.5a
  2.                             (C) 1991/92, Bill Dykstra
  3.                             -------------------------
  4.  
  5. -------------------------------------------------------------------------------
  6.  
  7. Notice: This program was previously called SELECT.  It has been renamed, as
  8. new versions of DOS now have a program called SELECT, and I did not want people
  9. to accidentally run the DOS SELECT when they were trying to run this program!
  10.         (Thanks Pete for pointing that out to me!)
  11.  
  12. -------------------------------------------------------------------------------
  13. GetKey is a small program designed to help enhance your batch files.  The
  14. program will wait for a user to press a key, and will then pass an errorlevel
  15. to DOS.  You may then use this errorlevel to find out which key was pressed, and
  16. act accordingly.
  17.  
  18. Usage:
  19. GETKEY "Prompt",Letters /NC /NE /NH /C(fg,bg) /L(line,col) /ANY...
  20.                      .../TIMEOUT=x /DEFAULT=x /EU /EL /ASCII /BEEP...
  21.                      .../BOX(line,col,h,w,fg,bg,border)
  22.  
  23.         Parameters may be entered in any order, BUT PLEASE NOTE that you may
  24.         NOT leave a space between any parts of a single parameter (with the
  25.         exception of the prompt parameter).  In other words, you cannot 
  26.         separate /L(line, col) with a space between the comma and the col
  27.         value.  The correct usage would be /L(line,col)... no spaces.
  28.         The same holds for all parameters.. NO spaces.  You MAY put spaces 
  29.         between the different parameters, and you may include spaces in your
  30.         prompt message.
  31.  
  32.         If you notice strange things appearing where your prompt should be, 
  33.         you may have placed a space somewhere where you should not have.
  34.  
  35.  
  36.         "Prompt" is any text you wish to have displayed.  For example, if you
  37.         wanted your batch file to wait for a selection to be made, you might
  38.         have the text:  "Make a Choice: "
  39.  
  40.         Letters:  any letters (keys) that are valid.  Ie. If you wanted someone
  41.                   to choose from three choices, (1, 2 and 3) then the letters
  42.                   would be:  ,123
  43.  
  44.                   Or to choose from A, B, C, or D you would have:
  45.                         ,AaBbCcDd   or if you specify /NC, which means that
  46.                         the case of the text is not important, then you would
  47.                         only need:   ,abcd
  48.  
  49.                   This list of letters is also referred to as a "keylist".
  50.              If you do NOT include a keylist, the program will display any
  51.              prompt (and boxes) that you specify, and will then exit.
  52.  
  53.         /NC  simply tells the program not to be case sensitive.  In other words,
  54.              it doesn't matter if the user presses 'A' or 'a'.
  55.              If you do NOT specify the /NC option, then 'A' and 'a' will be
  56.              two different keys!
  57.                  (/NC = No Case Check)
  58.  
  59.         /NH  this option will disable 'hotkeys'.  When hotkeys is on, which is
  60.              the default, then the user simply needs to press a valid key, and
  61.              the program will continue.  When the /NH option is specified, the
  62.              user must press ENTER before the program will resume.  If the user
  63.              types several letters at the prompt before pressing ENTER, only
  64.              the first letter will be recognized.  All others will be ignored.
  65.              eg:  if the user types HELLO only the H will be recognized.
  66.                 (/NH = No Hotkey)
  67.  
  68.  
  69.         /C(fg,bg):      If this option is specified, the prompt (if any) will
  70.                         be displayed in the color specified, where fg is the
  71.                         forground color and bg is the background color.
  72.  
  73.                         Valid ranges are: fg: 0-15 (add 16 for blinking)
  74.                                           bg: 0-9
  75.  
  76.         /L(line,col):   This allows you to specify where on the screen the
  77.                         prompt (if any) is to be displayed.
  78.                         Line: 1-24,  column: 1-80. (depending on screen mode!)
  79.  
  80.         /NE             This is the "No Echo" option.  If this option is
  81.                         specified, then the letter chosen by the user will
  82.                         NOT be displayed.  By default the letter chosen is
  83.                         displayed on the screen.     (/NE = No Echo)
  84.         
  85.         /EU             This option will cause the letter that you select to
  86.                         be displayed in UPPER CASE.  (/EU = Echo Upper)
  87.  
  88.         /EL             This option will cause the letter that you select to
  89.                         be displayed in LOWER CASE.  (/EL = Echo Lower)
  90.  
  91.         /TIMEOUT=x      This is the timeout option.  You may specify /T=x
  92.                         if you prefer.  This option will tell the program to
  93.                         time out after x number of seconds if no input is
  94.                         received from the keyboard.  NOTE that if you do NOT 
  95.                         specify a default key (see /DEFAULT=x later in the
  96.                         documentation) then NO action will be taken when the
  97.                         time limit has expired...ie, it will continue waiting!
  98.  
  99.  
  100.         /ANY            This option allows you to wait for ANY key to be
  101.                         pressed, rather than waiting for a specific key.
  102.                         The character of the key you press will NOT be
  103.                         displayed when it is pressed.
  104.  
  105.                         Note that the possible selections you give in the
  106.                         LETTERS section (following the comma) will be ignored.
  107.  
  108.                    **   NOTE: If the ESC key is pressed the program will exit
  109.                    **   with an errorlevel of 10.  If any other key is pressed,
  110.                    **   the program will exit with no errorlevel.(0)
  111.  
  112.  
  113.  
  114.         /ASCII          This options will COMPLETELY change the ERRORLEVEL
  115.                         system.  Normally, when an option is selected, the
  116.                         errorlevel returned is based on its position in the
  117.                         list of available keys (the keylist).  For example, if
  118.                         the third letter in the keylist was chosen, then
  119.                         errorlevel 3 would be returned.  If the /ASCII option
  120.                         (/ASC for short) is used, THE ASCII VALUE OF THE
  121.                         KEY PRESSED will be returned as the errorlevel!
  122.                         
  123.                         Eg:  GETKEY "Choose Y or N: ",yn /ASCII
  124.                         If y is pressed, errorlevel 121 is returned.
  125.                  
  126.                         Some similar programs that wait for keypresses work
  127.                         entirely on this method, and you may find it useful.
  128.  
  129.                         PLEASE NOTE THESE EXCEPTIONS:
  130.  
  131.                           - When the /ANY option is used AND the /ASCII option
  132.                             is used, the program will return the ASCII value
  133.                             of the key pressed.  It will NOT return an
  134.                             ERRORLEVEL 10 when the ESC key is pressed, as it
  135.                             normally would.  (Instead, ESC would return 
  136.                             ERRORLEVEL 27!)
  137.  
  138.                           - When the /NC (ignore case) option is used, the
  139.                             ASCII value returned will be based on how the
  140.                             character is displayed.  By default, when the
  141.                             /NC option is used, all letters are converted to
  142.                             UPPER CASE.  Thus, the ASCII value of a letter
  143.                             pressed would be the ASCII value of the UPPER CASE 
  144.                             of that letter. (ie, if you press 'a', the value of
  145.                             'A' will be returned).  If you have the /EL option
  146.                             in use (echo lower case), then the value of the
  147.                             letter in LOWER CASE will be returned.
  148.  
  149.         /BEEP           When you specify the /BEEP option, the computer will
  150.                         sound a beep whenever an invalid key is pressed.
  151.  
  152.         /DEFAULT=x      This will allow you to use a default key.  If ENTER is
  153.                         pressed, this default key will be used.  For example
  154.                         if you have two choices, 1 and 2, and choice 2 is
  155.                         almost always chosen, you could make this the default.
  156.                         By pressing ENTER, choice 2 would be selected!
  157.  
  158.         /BOX(line,col,h,w,fg,bg,border)
  159.  
  160.                         This feature was added to GetKey when version 2.5a was
  161.                         created.  This will draw a box on the screen, with the
  162.                         box's upper left corner at the line and column numbers
  163.                         specified.  There height will be 'h' lines, and the
  164.                         width will be 'w' columns.  The box will be in colour
  165.                         FG on BG, with a border style of 'border', which can be
  166.                         from 0 - 8.   Be sure you leave NO spaces anywhere when
  167.                         passing the box's parameters.  Separate each number
  168.                         with a comma only.. NO spaces!    You may have up
  169.                         to five (5) boxes specified on the command line.   If
  170.                         you want to draw only a box, without waiting for a key,
  171.                         just specify the /BOX parameter, without providing a 
  172.                         keylist.  If no keylist is found, the box will be drawn
  173.                         and the program will exit.
  174.  
  175.                         The line and column parameters must be in the 1-25 and
  176.                         1-80 range respectively.  The FG (foreground) colour
  177.                         must be from 0-15, and the BG (background) colour must
  178.                         be from 0-7.   The border must be from 0-8.  If you use
  179.                         values out of these ranges, odds are the box simply
  180.                         will not be displayed.
  181.                         
  182.                         Border Styles:   
  183.                              0 = no border.
  184.                              1 = single line all around.
  185.                              2 = double line all around.
  186.                              3 = double line on top & bottom, single on sides
  187.                              4 = single line on top & bottom, double on sides
  188.                              5 = box made with the ░ char
  189.                              6 = box made with the ▒ char
  190.                              7 = box made with the ▓ char
  191.                              8 = box made with the █ char
  192.  
  193.  
  194. Special Keys:
  195.  
  196.         Sometimes it is handy to be able to use the Spacebar or ESC
  197.         key as an option, rather than for their normal use.  If you want to use 
  198.         one of these as an option, the following characters may be placed in
  199.         your keylist.
  200.  
  201.         ~ :Use the spacebar as an option.
  202.         ^ :Use the ESCape key as an option.
  203.  
  204. ************************** ERRORLEVELS
  205.  
  206. When the program terminates, an errorlevel is passed to the operating system.
  207. This errorlevel can be used in your batch files to determine what will happen
  208. next.
  209.  
  210. The best way to show how this works is with an example.  Please note that you
  211. MUST start at the highest errorlevel and count BACKWARDS to 1!
  212.  
  213. The first letter in your list of selections will have a value of errorlevel 1.
  214. The second of 2, and so on...
  215.  
  216.  
  217. SAMPLE BATCH FILE:
  218.  
  219.         @ECHO OFF
  220.         :TOP
  221.         CLS
  222.         ECHO                    ** Menu **
  223.         ECHO            A.  Run WordPerfect
  224.         ECHO            B.  Run MS Works
  225.         ECHO            C.  Run Pacman
  226.         ECHO            X.  Exit to DOS
  227.         GETKEY "Please make your choice: ",abcx /C(14,0) /NC /DEFAULT=b /t=120
  228.         if errorlevel 4 goto exit
  229.         if errorlevel 3 goto pacman
  230.         if errorlevel 2 goto works
  231.         if errorlevel 1 goto wp
  232.         goto top
  233.         :wp
  234.         CD C:\WP51
  235.         WP
  236.         goto top
  237.         :pacman
  238.         CD C:\PACMAN
  239.         PACMAN
  240.         goto top
  241.         :works
  242.         CD C:\WORKS
  243.         WORKS
  244.         goto top
  245.         :exit
  246.         =========================END OF FILE
  247.  
  248.         In the above example, you will notice four GOTO commands, followed by
  249.         the name (or LABEL) of where they will branch.  These labels can be
  250.         found furthur on in the batch file.  Notice that they are preceded by
  251.         a colon (:).  The commands following each label may be any commands
  252.         you need to execute the program you want to run.  Note that the LAST
  253.         command in each section is GOTO TOP.  This will re-run this menu
  254.         batch file when you exit the program you have run. (:TOP is at the top
  255.         of the file)
  256.  
  257.         Note that the /NC option is used, so it doesn't matter whether the
  258.         user presses 'a' or SHIFT 'A'.  If you do not use /NC then, in this
  259.         example, only small a, b, c, and x would have an effect!
  260.  
  261.         Also note that you could press ENTER to select choice 'b', as
  262.         'b' was selected as the default.  NOTE YOU CANNOT LEAVE A SPACE
  263.         BETWEEN THE WORD 'DEFAULT' and the '=' sign and the default letter!
  264.         ie:  DEFAULT = a   is unacceptable!
  265.              DEFAULT=a is fine!!!!!!!!!!!!
  266.  
  267.         If NO input is received from the keyboard after 120 seconds (/t=120),
  268.         then the default choice will automatically be made!
  269.  
  270.         For more information regarding the GOTO command, ERRORLEVELS, and other
  271.         DOS batch file commands, please refer to your DOS reference manual.  If
  272.         you have a PIRATED copy of DOS, and have no manual, too bad! I feel no
  273.         pity!!  <GRIN>
  274.  
  275.  
  276.         SOME MORE EXAMPLES:
  277.         ==================
  278.  
  279. I have added some more examples, as some of the option combinations have 
  280. become quite complicated to explain clearly.
  281.  
  282. (1)     GETKEY "Press any key... " /ANY
  283.  
  284.         Errorlevel 0 will be returned for all actions, unless ESC is pressed.
  285.         IF ESC is pressed, Errorlevel 10 is returned.
  286.  
  287. (2)     GETKEY "Press any key... " /ANY /ASCII
  288.  
  289.         The errorlevel of the key pressed will be returned, REGARDLESS of what
  290.         key is pressed.
  291.                 If 'a' is pressed, 97 is returned
  292.                 If 'A' is pressed, 65 is returned
  293.                 If ESC is pressed, 27 is returned
  294.                 If SPACE is pressed, 32 is returned
  295.  
  296.  
  297. (3)     GETKEY "Press any key... " /ANY /ASCII /EU
  298.  
  299.         This is the same as the second example, except pressing 'a' and
  300.         pressing 'A' will both return errorlevel 65.  ALL letters are 
  301.         converted to UPPER CASE values.
  302.         If /EL was used, all letters would be converted to lower case values.
  303.  
  304. (4) GETKEY "Choose A,B,C,D or SPACEBAR: ",abcd~ /NC /EL /C(14,0) /DEF=B /T=30
  305.  
  306.                 In this case, the prompt is displayed in yellow (on black).
  307.                 Case checking is OFF.  Ie, 'A' or 'a' will work.
  308.                 All letters will be echoed in LOWER case.
  309.  
  310.                 '~' will return errorlevel 5    (space bar)
  311.                 'D' will return errorlevel 4
  312.                 'C' will return errorlevel 3
  313.                 'B' will return errorlevel 2
  314.                 'A' will return errorlevel 1
  315.  
  316.                 If no choice is made in 30 seconds, 'B' is chosen
  317.                 automatically.  If ENTER is pressed, 'B' is also chosen.
  318.                 (/DEF=B means B is the default)
  319.  
  320.  
  321.  
  322. (5)  Another Sample Batch file... TRY THIS ONE OUT!
  323. --------------top of file-------------
  324. @echo off
  325. cls
  326. getkey "Isn't This Great!?" /l(9,32) /c(15,4) /box(5,5,10,70,15,1,2) /box(7,10,6,60,14,4,7)
  327. getkey "[  Press ESC to Exit  ]" ,^ /ne /l(14,30) /c(15,1)
  328. echo"
  329. echo"
  330. --------------end of file-------------
  331.  
  332.  
  333.  
  334. ******************************************************************************
  335.  
  336. Revision history:
  337.  
  338.         ver 1.00beta - 1.2 : The first releases of GetKey.  The program was
  339.         called SELECT at this time, and was written in Turbo Pascal 6.0.
  340.  
  341.         ver 2.0 - totally rewrote the program with Turbo C++ 3.0, thus fixing
  342.                   bugs, speeding it up, and adding options.
  343.  
  344.         ver 2.4a - added the /ASCII option
  345.         ver 2.4b - added the /BEEP option
  346.         ver 2.4c - fixed a little bug.. (AAAAAAARG!)
  347.                    When using the SPACEBAR as a valid key in the keylist,
  348.                    (ie, using the '~' character), if the SPACEBAR (~) was
  349.                    set as the default key (/DEF=~) then the program would
  350.                    get stuck in a loop..  minor logic error.  Sorry!
  351.                    I found this one myself.. locked up my BBS batch file the
  352.                    other day...
  353.         ver 2.5a - Added the /BOX option and also allowed the program to
  354.                    display the prompt even if a keylist was not specified (this
  355.                    is handy for echoing colour text on screen in batch files).
  356.                    Special thanks to Ray (of Montclair, New Jersey) for this
  357.                    /BOX suggestion!  I hope it accomplishes what you were
  358.                    looking for...
  359.  
  360. ******************************************************************************
  361.  
  362. This program is freeware.   Go ahead and copy it, give it away or even lose it.
  363. You may NOT sell it!  This program MAY be distributed as part of a FREE
  364. "add-on" package with other software in packages such as computer systems, etc,
  365. but ONLY if the program and unmodified documentation are distributed together.
  366. PLEASE notify me if you do this.  (just because I would like to know!).
  367.  
  368. Please distribute the documentation (as poor as it may be!) with the program!
  369.  
  370. If you use this program on a regular basis, I would appreciate if you let me
  371. know that you like it.  This is the only form of 'registration' for which
  372. I ask.  I just want to know if further developement is worthwhile.  Thanks.
  373.  
  374. Other software by the author, such as PhoneIt 6.0,  EasyMenu 3.0, and a few
  375. other wierd and small utilities may be found on the author's BBS.
  376.  
  377.      The BillBoard BBS:  (416) 898-2443
  378.                          Newmarket, Ontario
  379.                          1200-14,400 baud, v.32bis/v.42bis MNP 2-5.  N,8,1
  380.                          800MB ONLINE!  Over 2.5 gigs total!
  381.  
  382.  
  383. Feel free to leave me a note if you have any suggestions, complaints (which
  384. I'll just delete... ) questions, or just want to leave mail so I'll have
  385. something to read!  Address mail to BILL DYKSTRA.
  386.  
  387. Thanks!
  388.  
  389. The Pascal (GetKey version 1.2, also known as SELECT) and Turbo C (GetKey 2.x)
  390. source code files may be available upon request.
  391.  
  392.      --Bill
  393.